OpenClaw 子代理管理完全指南

在复杂任务中，单个 AI 助理可能不够用。OpenClaw 支持创建和管理多个子代理（subagents），实现任务并行处理、专业分工和复杂工作流编排。

一、为什么需要子代理？

典型场景

1. 并行任务处理：同时处理多个独立任务
2. 专业分工：不同代理专注不同领域（代码、写作、数据分析）
3. 复杂工作流：将大任务分解为多个子任务
4. 资源隔离：不同任务使用不同模型配置

架构示意

主代理 (你)
├── 子代理 1 (代码审查)
├── 子代理 2 (文档编写)
└── 子代理 3 (测试执行)

二、核心概念

1. sessions_spawn - 创建子代理

sessions_spawn(
  task="分析这个 Python 项目的代码质量",
  runtime="subagent",      // 或 "acp" 用于 ACP 编码会话
  mode="run",              // "run" 一次性执行，"session" 持久会话
  agentId="code-reviewer", // 指定代理类型
  model="qwen-max",        // 可选：指定模型
  timeoutSeconds=300,      // 超时时间
  streamTo="parent"        // 结果流式返回给父代理
)

2. subagents - 管理子代理

// 查看所有子代理
subagents(action="list")

// 给子代理发送新指令
subagents(action="steer", target="agent-123", message="请优先处理测试文件")

// 终止子代理
subagents(action="kill", target="agent-123")

3. sessions_yield - 等待子代理完成

// 生成子代理后，让出执行权等待结果
sessions_spawn(task="...", mode="run")
sessions_yield()  // 等待子代理完成并返回结果

三、实战案例 1：并行代码审查

场景

提交了一个包含多个模块的 PR，需要同时审查代码质量、安全漏洞和性能问题。

实现代码

// 1. 并行启动 3 个专业审查代理
sessions_spawn(
  task="审查 /src/api/ 目录的代码质量和最佳实践",
  agentId="code-reviewer",
  mode="run",
  label="code-quality"
)

sessions_spawn(
  task="检查 /src/api/ 目录的安全漏洞（注入、认证、授权）",
  agentId="security-auditor", 
  mode="run",
  label="security-audit"
)

sessions_spawn(
  task="分析 /src/api/ 目录的性能问题和优化建议",
  agentId="performance-analyst",
  mode="run",
  label="performance-review"
)

// 2. 等待所有代理完成
sessions_yield()

// 3. 收集并整合结果
// 此时会收到所有子代理的完成通知和结果

结果整合

📊 代码审查报告

【代码质量】✅ 良好
- 遵循 PEP8 规范
- 函数命名清晰
- 建议：添加更多类型注解

【安全审计】⚠️ 发现 2 个问题
- /src/api/auth.py: SQL 注入风险（第 45 行）
- /src/api/upload.py: 文件上传未限制类型

【性能分析】💡 优化建议
- 数据库查询可添加缓存
- 循环内避免重复计算

四、实战案例 2：多步骤内容创作工作流

场景

创建一篇完整的技术博客，需要：调研→大纲→写作→校对→发布

实现代码

// 步骤 1：市场调研
research_result = sessions_spawn(
  task="调研 2026 年 AI Agent 领域的热门话题和趋势",
  mode="run",
  streamTo="parent"
)
sessions_yield()

// 步骤 2：基于调研结果创建大纲
outline_result = sessions_spawn(
  task=f"根据以下调研结果创建博客大纲：{research_result}",
  mode="run",
  streamTo="parent"
)
sessions_yield()

// 步骤 3：撰写正文
draft_result = sessions_spawn(
  task=f"根据以下大纲撰写 3000 字博客：{outline_result}",
  agentId="technical-writer",
  mode="run",
  streamTo="parent"
)
sessions_yield()

// 步骤 4：技术校对
review_result = sessions_spawn(
  task=f"校对以下技术内容的准确性：{draft_result}",
  agentId="technical-reviewer",
  mode="run",
  streamTo="parent"
)
sessions_yield()

// 步骤 5：最终整理并发布
publish(draft_result + review_result)

五、实战案例 3：智能客服系统

场景

构建一个能同时处理多个客户咨询的客服系统。

实现代码

// 客服代理工厂函数
function create_customer_service_agent(customer_id, inquiry) {
  return sessions_spawn(
    task=`处理客户 ${customer_id} 的咨询：${inquiry}`,
    agentId="customer-service",
    mode="session",  // 持久会话，可进行多轮对话
    label=`cs-${customer_id}`,
    thread=true      // 线程隔离
  )
}

// 同时处理 5 个客户咨询
const customers = [
  {id: "C001", inquiry: "如何重置密码？"},
  {id: "C002", inquiry: "订单什么时候发货？"},
  {id: "C003", inquiry: "产品保修政策是什么？"},
  {id: "C004", inquiry: "如何申请退款？"},
  {id: "C005", inquiry: "技术支持联系方式？"}
]

customers.forEach(c => create_customer_service_agent(c.id, c.inquiry))

// 监控所有客服会话状态
subagents(action="list", recentMinutes=30)

六、高级技巧

1. 子代理间通信

// 子代理 1 分析数据
data_agent = sessions_spawn(
  task="分析销售数据，找出趋势",
  mode="session",
  label="data-analyst"
)

// 子代理 2 生成报告
report_agent = sessions_spawn(
  task="等待数据分析师的结果，然后生成可视化报告",
  mode="session", 
  label="report-generator"
)

// 主代理协调通信
sessions_send(sessionKey=data_agent.sessionKey, message="开始分析")
// ...等待结果...
sessions_send(sessionKey=report_agent.sessionKey, message=`数据结果：${data_result}`)

2. 资源限制和超时

// 设置严格的资源限制
sessions_spawn(
  task="快速检查语法错误",
  timeoutSeconds=60,        // 1 分钟超时
  runTimeoutSeconds=300,    // 运行超时
  thinking="off"            // 禁用深度思考，加快速度
)

3. 错误处理和重试

// 带重试的子代理调用
function spawn_with_retry(task, max_retries=3) {
  for (let i = 0; i < max_retries; i++) {
    try {
      const result = sessions_spawn(task, mode="run")
      sessions_yield()
      return result
    } catch (e) {
      console.log(`重试 ${i+1}/${max_retries}`)
      if (i === max_retries - 1) throw e
    }
  }
}

七、最佳实践

1. 何时使用子代理

✅ 适合：

• 任务可并行化
• 需要不同专业技能
• 任务执行时间较长
• 需要隔离上下文

❌ 不适合：

• 简单一次性任务
• 需要紧密协调的多步骤任务
• 资源受限环境

2. 命名和标签

// 好的命名
sessions_spawn(task="...", label="code-review-20260319")
sessions_spawn(task="...", label="security-audit-auth-module")

// 避免模糊命名
sessions_spawn(task="...", label="agent1")  // ❌

3. 清理资源

// 定期清理完成的子代理
const agents = subagents(action="list")
agents.forEach(agent => {
  if (agent.status === "completed" && agent.finishedAt < Date.now() - 3600000) {
    subagents(action="kill", target=agent.id)
  }
})

八、常见问题

Q: 子代理和主代理共享什么资源？

A: 子代理继承主代理的工作目录，但有独立的会话历史和工具调用权限。

Q: 如何调试子代理？

A: 使用 sessions_history(sessionKey=xxx) 查看子代理的完整执行历史。

Q: 子代理可以创建自己的子代理吗？

A: 可以，但建议限制嵌套层级（不超过 3 层）以避免复杂性爆炸。

Q: 如何控制成本？

A:

1. 设置合理的超时时间
2. 使用适当的模型（简单任务用小模型）
3. 及时清理完成的子代理

九、总结

子代理是构建复杂 AI 应用的核心能力：

特性	说明
并行处理	同时执行多个任务
专业分工	不同代理专注不同领域
资源隔离	独立会话和上下文
灵活编排	支持复杂工作流

掌握子代理管理，你可以构建出真正智能的多代理系统。

---

相关资源：

• sessions_spawn API 参考
• subagents 工具详解
• 多代理系统设计模式